/*----------------------------------------------------------------------------
The contents of this file are subject to the Mozilla Public License
Version 1.1 (the "License"); you may not use this file except in
compliance with the License. You may obtain a copy of the 
License at http://www.mozilla.org/MPL/
	
Software distributed under the License is distributed on 
an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, 
either express or implied. 
See the License for the specific language governing rights and 
limitations under the License.
	
The Original Code is Fever RS ( ActionScript 3 ) Framework code.
	
The Initial Developer of the Original Code is Romain Ecarnot.
Portions created by Initial Developer are Copyright (C) 2006
the Initial Developer. All Rights Reserved.
	
Contributor(s):
	
Unless required by applicable law or agreed to in writing, 
software distributed under the License is distributed on 
an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS 
OF ANY KIND, either express or implied.
See the License for the specific language governing permissions 
and limitations under the License.
----------------------------------------------------------------------------*/

package fever.core 
{
	import flash.display.Sprite;
	import flash.display.Stage;
	
	import com.bourre.commands.FrontController;
	import com.bourre.plugin.Plugin;
	
	import fever.app.context.ApplicationContainer;
	import fever.app.context.ApplicationDialog;
	import fever.app.context.ContextBuilderStrategy;
	import fever.plugin.PluginResources;	

	/**
	 * Dispatched when the application is resized.
	 *
	 * @eventType fever.events.FeverEvent.onResizeEVENT
	 */
	[Event(name="onResize", type="fever.events.FeverEvent")]

	/**
	 * Dispatched when the application is moved.
	 *  
	 * <p>Not available in all application context</p>.
	 *
	 * @eventType fever.events.FeverEvent.onMoveEVENT
	 */
	[Event(name="onMove", type="fever.events.FeverEvent")]

	/**
	 * Dispatched when the application's title changed.
	 *  
	 * @eventType fever.events.FeverEvent.onTitleChangeEVENT
	 */
	[Event(name="onTitleChange", type="fever.events.FeverEvent")]

	/**
	 * Dispatched every 100 milliseconds when there has been no keyboard
	 * or mouse activity for 5 second.
	 * 
	 * @see fever.core.FeverCore#IDLE_INTERVAL
	 * @see fever.core.FeverCore#IDLE_THRESHOLD
	 *  
	 *  @eventType fever.events.FeverEvent.onIdleEVENT
	 */
	[Event(name="onIdle", type="fever.events.FeverEvent")]
	
	/**
	 * Dispatched when mouse enter application.
	 * 
	 * @eventType fever.events.FeverEvent.onMouseEnterEVENT
	 */
	[Event(name="onMouseEnter", type="fever.events.FeverEvent")]
	
	/**
	 * Dispatched when mouse leave application.
	 * 
	 * @eventType fever.events.FeverEvent.onMouseLeaveEVENT
	 */
	[Event(name="onMouseLeave", type="fever.events.FeverEvent")]
	
	/**
	 * Fever <strong>RS Core</strong> interface.
	 * 
	 * @example
	 * <listing version="3.0">
	 * 
	 * 	RSCore.init( this, BrowserBuilder );
	 * </listing>
	 * 
	 * <p><strong>RS Core</strong> is a <strong>Lowra</strong> plugin extension, it act as 
	 * a basic <strong>Lowra</strong> plugin and have same features and possibilities :
	 * <ul>
	 *  <li>Is registred in <strong>Lowra BeanFactory</strong> with 
	 *   <code>"FeverCoreBean"</code> identifier.</li>
	 *   <li>Channel is registred in <strong>Lowra ChannelExpert</strong> 
	 *   manager with <code>"FeverCoreChannel"</code> name.</li>
	 *   <li><strong>Lowra DisplayObjectExpert</strong> root target is populate 
	 *   with <strong>core</strong> root sprite.</li>
	 *  <br />
	 * 	<li><strong>Logging</strong> support with : <code>RSCore.getLogger()</code> method</li>
	 * 	<li><strong>Front controler</strong> using : <code>RSCore.getController()</code> method</li>	 * 	<li><strong>Event</strong> support with : <code>RSCore.firePublicEvent()</code>, <code>RSCore.firePrivateEvent()</code>, 
	 * 	<code>RSCore.fireExternalEvent()</code> methods</li>
	 * 	<li><strong>MVC</strong> support with : <code>RSCore.getModelLocator()</code>, <code>RSCore.getViewLocator()</code> 
	 * 	methods</li>
	 * 	<li>And <strong>Fever</strong> Resouces API with : <code>RSCore.getResources()</code> method.</li>
	 * </ul>
	 * 
	 * <p>Using <strong>RS Core</strong> as "main loader" application in <strong>Lowra I.O.C.</strong> 
	 * project architecure is a possible ( good ) choice.</p>
	 * 
	 * @example 
	 * <listing version="3.0">
	 * 
	 * package  
	 * {
	 * 	import flash.display.Sprite;
	 * 	
	 * 	import com.bourre.ioc.load.ApplicationLoader;
	 * 	import com.bourre.ioc.load.ApplicationLoaderListener;
	 * 	import com.bourre.load.LoaderEvent;
	 * 	import com.bourre.log.Logger;
	 * 	
	 * 	import fever.app.context.browser.BrowserBuilder;
	 * 	import fever.core.FeverCore;
	 * 	import fever.core.RSCore;
	 * 	import fever.error.CoreEngineException;
	 * 	import fever.log.FirebugLayout;	
	 * 
	 * 	public class Test extends Sprite implements ApplicationLoaderListener
	 * 	{
	 * 		public function Test( )
	 * 		{
	 * 			Logger.getInstance( ).addLogListener( FirebugLayout );
	 * 			
	 * 			try
	 * 			{
	 * 				RSCore.run( this, BrowserBuilder );
	 * 				
	 * 				var loader : ApplicationLoader = new ApplicationLoader();
	 * 				loader.addListener( this );
	 * 				loader.load( );
	 * 			}
	 * 			catch( e : CoreEngineException )
	 * 			{
	 * 				RSCore.getLogger().error( e.message );	
	 * 			}
	 * 		}
	 * 
	 * 		public function onApplicationBuilt( e : LoaderEvent ) : void
	 * 		{
	 * 		}
	 * 		
	 * 		public function onApplicationInit( e : LoaderEvent ) : void
	 * 		{
	 * 			RSCore.trackLink( "startPoint" );
	 * 		}
	 * 		
	 * 		public function onLoadStart(e : LoaderEvent) : void
	 * 		{
	 * 		}
	 * 		
	 * 		public function onLoadInit(e : LoaderEvent) : void
	 * 		{
	 * 		}
	 * 		
	 * 		public function onLoadProgress(e : LoaderEvent) : void
	 * 		{
	 * 		}
	 * 		
	 * 		public function onLoadTimeOut(e : LoaderEvent) : void
	 * 		{
	 * 			RSCore.getLogger().info( e.type );
	 * 		}
	 * 		
	 * 		public function onLoadError(e : LoaderEvent) : void
	 * 		{
	 * 			RSCore.getLogger().info( e.type );
	 * 		}
	 * 	}
	 * } 
	 * </listing>
	 * 
	 * @author Romain Ecarnot
	 */
	public interface FeverCore extends Plugin
	{
		//--------------------------------------------------------------------
		// Public properties
		//--------------------------------------------------------------------
		
		/**
		 *  The number of milliseconds between each 'idle' checking.
		 *  
		 *  @default 100  
		 */
		function get IDLE_INTERVAL( ) : Number;

		/** @private */
		function set IDLE_INTERVAL( n : Number ) : void;

		/**
		 *  The number of milliseconds that must pass without any user 
		 *  activity before Fever dispatchs <code>FeverEvent.onIdleEVENT</code> 
		 *  event.
		 *  
		 *  @default 5000
		 */
		function get IDLE_THRESHOLD( ) : Number;

		/** @private */
		function set IDLE_THRESHOLD( n : Number ) : void;
		
		/** 
		 * Returns main application sprite container.
		 */
		function get root() : Sprite; 
		
		/**
		 * Returns root stage of application
		 */
		function get stage() : Stage;
		
		/**
		 * Gives access to application <strong>container</strong>.
		 * 
		 * @see fever.app.context.ApplicationContainer
		 */
		function get window() : ApplicationContainer;

		/**
		 * Gives access to application <strong>dialog</strong> system.
		 * 
		 * @see fever.app.context.ApplicationDialog
		 */
		function get dialog() : ApplicationDialog;
		
		
		//--------------------------------------------------------------------
		// Public API
		//--------------------------------------------------------------------
		
		/**
		 * Returns core configuration.
		 */
		function getResources() : PluginResources

		/**
		 * Inits application.
		 * 
		 * @param target Main application <strong>Sprite</strong>
		 * @param strategy Strategy to use to init correct application 
		 * context ( default use <code>BrowserBuilderStrategy</code> )<br />
		 * Some Fever implemented context builder :
		 * <ul>
		 *   <li><strong>Web browser</strong> context.</li>
		 *   <li><strong>Adobe AIR</strong> context.</li>
		 *   <li><strong>Northcode SWF Studio</strong> context.</li>
		 *   <li><strong>mcm Zinc</strong> context.</li>
		 * </ul></p>
		 * 
		 * @return <code>true</code> if all initializations are ok
		 * 
		 * @throws fever.error.CoreEngineException if initialization 
		 * failed
		 * 
		 * @see fever.app.context		 * @see fever.app.context.air		 * @see fever.app.context.browser		 * @see fever.app.context.swfs		 * @see fever.app.context.zinc
		 */
		function run( target : Sprite, strategy : ContextBuilderStrategy = null ) : Boolean;
		
		/**
		 * Returns application argument associated with 
		 * <code>id</code> identifier.
		 * 
		 * @param id Argument identifier 
		 */
		function getArgument( id : String ) : String;
		
		/**
		 * Track link throw <strong>Analytic I.O.C plugin</strong>.
		 * 
		 * <p><span class="label">Overloading</span>
		 * <ul>
		 *   <li>trackLink( e : AnalyticEvent )</li>
		 *   <li>trackLink( url : String, type : String )</li>
		 * </ul></p>
		 * 
		 * @example using url and type arguments :
		 * <listing version="3.0">
		 * 
		 *   RSCore.trackLink( "doc/myPDF.pdf", AnalyticLinkType.DOWNLOAD_LINK );
		 * </listing>
		 * 
		 * @example using <code>AnalyticEvent</code> event :
		 * <listing version="3.0">
		 * 
		 *   var e : AnalyticEvent = new AnalyticEvent(
		 *   	AnalyticEvent.onTrackLinkEVENT,
		 *   	"doc/myPDF.pdf",
		 *   	AnalyticLinkType.DOWNLOAD_LINK
		 *   );
		 *   RSCore.trackLink( e );
		 * </listing>
		 * 
		 * <p><strong>AnalyticPlugin</strong> can be loaded by <strong>I.O.C.</strong> 
		 * application context xml file, or automatically by the 
		 * <strong>Fever RS</strong> core if Analytic plugin is not already loaded.</p>
		 * 
		 * @example <strong>I.O.C.</strong> application context
		 * <listing version="3.0">
		 * 
		 * &lt;beans&gt;
		 * 	
		 * 	&lt;dll id="ap" url="resources/dll/AnalyticPlugin.swf" /&gt;
		 * 	&lt;dll id="apg" url="resources/dll/GoogleAnalyticStrategy.swf" /&gt;
		 * 	
		 * 	&lt;object id="GoogleAnalytic" type="fever.plugin.analytic.strategy.GoogleAnalytic" /&gt;
		 * 	
		 * 	&lt;plugin id="analytic" channel="MyAnalyticChannel" type="fever.plugin.analytic.AnalyticPlugin"&gt;
		 * 		&lt;method-call name="register"&gt;
		 * 			&lt;argument ref="GoogleAnalytic" /&gt;
		 * 		&lt;/method-call&gt;
		 * 	&lt;/plugin&gt;
		 * 	
		 * &lt;/beans&gt;
		 * </listing>
		 * 
		 * <p>If no <strong>I.O.C.</strong> is used, <strong>Fever RS</strong> automatically 
		 * call <strong>PluginRuntimeLoader.loadClass(...)</strong> to load the plugin.<br />
		 * Thus, plugin channel is available and tracking works properly as plugin was loaded.</p>
		 * 
		 * @param arguments Overloading support
		 * 
		 * @see fever.plugin.PluginRuntimeLoader
		 */
		function trackLink( ...arguments ) : void;
		
		/**
		 * Save history state throw <strong>History I.O.C plugin</strong>.
		 * 
		 * <p><span class="label">Overloading</span>
		 * <ul>
		 *   <li>setHistoryStatus( e : HistoryEvent )</li>
		 *   <li>setHistoryStatus( o : HistoryStatus )</li>
		 *   <li>setHistoryStatus( deepLink : String )</li>
		 *   <li>setHistoryStatus( deepLink : String, data : Object )</li>
		 * </ul></p>
		 * 
		 * @example
		 * <listing version="3.0">
		 * 
		 *   var histStatus : HistoryStatus = new HistoryStatus( "contact/romain" );
		 *   
		 *   var hisEvent : HistoryEvent = new HistoryEvent( 
		 *   	HistoryEvent.onRegisterHistoryEVENT, histStatus );
		 *   
		 *   //Four possibilities
		 *   //RSCore.saveHistory( "about/" + ( new Date() ).getTime().toString() );
		 *   //RSCore.saveHistory( "about/" + ( new Date() ).getTime().toString(), "Romain Ecarnot" );
		 *   //RSCore.saveHistory( histStatus );
		 *   //RSCore.saveHistory( hisEvent );
		 * </listing>
		 * 
		 * @param arguments Overloading support
		 */
		function saveHistory( ...arguments ) : void;
		
		/** 
		 * Indicates if application running online or not.
		 */
		function isOnline() : Boolean;
		
		/**
		 * Adds passed-in <code>listener</code> for receiving passed-in event 
		 * event <code>type</code>.
		 * 
		 * <p>Events are broadcasted throw <strong>public</strong> core channel.</p>
		 * 
		 * @param type Name of the Event.
		 * @param listener Listener object.
		 * @param rest Optional parameters
		 */
		function addEventListener( type : String, listener : Object, ...rest ) : Boolean;

		/**
		 * Removes passed-in <code>listener</code> that suscribed for 
		 * passed-in event <code>type</code>.
		 * 
		 * @param type Name of the Event.
		 * @param listener Listener object.
		 */
		function removeEventListener( type : String, listener : Object ) : Boolean;

		/**
		 * Returns core controller.
		 */
		function getController() : FrontController;

		/**
		 * Returns string representation.
		 */
		function toString() : String;
	}
}
